* gtk/gtkdialog.c, gtk/gtkrc.c, gtk/gtkwidget.c: Markup fixes.
* gdk-pixbuf-io.c: Markup fixes.
* gdk-pixbuf/tmpl/scaling.sgml, gdk/tmpl/fonts.sgml,
gdk/tmpl/general.sgml, gdk/tmpl/rgb.sgml, gdk/tmpl/visuals.sgml,
gdk/tmpl/windows.sgml, gtk/gtk-docs.sgml, gtk/tmpl/gtkaccellabel.sgml,
gtk/tmpl/gtkcombo.sgml, gtk/tmpl/gtkdialog.sgml,
gtk/tmpl/gtkdrawingarea.sgml, gtk/tmpl/gtkeditable.sgml,
gtk/tmpl/gtkfilesel.sgml, gtk/tmpl/gtkfontseldlg.sgml,
gtk/tmpl/gtkimage.sgml, gtk/tmpl/gtkmain.sgml, gtk/tmpl/gtkmenu.sgml,
gtk/tmpl/gtkmessagedialog.sgml, gtk/tmpl/gtkobject.sgml,
gtk/tmpl/gtkpaned.sgml, gtk/tmpl/gtkradiobutton.sgml,
gtk/tmpl/gtkrc.sgml, gtk/tmpl/gtkscale.sgml, gtk/tmpl/gtksignal.sgml,
gtk/tmpl/gtksocket.sgml, gtk/tmpl/gtkspinbutton.sgml,
gtk/tmpl/gtktogglebutton.sgml, gtk/tmpl/gtksignal.sgml,
gtk/tmpl/gtktooltips.sgml, gtk/tmpl/gtkwindow.sgml,
gdk/tmpl/regions.sgml, gtk/tmpl/gtkfontsel.sgml,
gtk/tmpl/gtkpixmap.sgml, gtk/tmpl/gtkprogress.sgml,
gtk/tmpl/gtkselection.sgml, gtk/tmpl/gtktable.sgml,
gtk/tmpl/gtktipsquery.sgml: Markup fixes (mainly examples).
+2001-12-13 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdialog.c, gtk/gtkrc.c, gtk/gtkwidget.c: Markup fixes.
+
Thu Dec 13 20:37:27 2001 Kristian Rietveld <kris@gtk.org>
* gtk/gtktreeview.c (gtk_tree_view_button_press): do not try
+2001-12-13 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdialog.c, gtk/gtkrc.c, gtk/gtkwidget.c: Markup fixes.
+
Thu Dec 13 20:37:27 2001 Kristian Rietveld <kris@gtk.org>
* gtk/gtktreeview.c (gtk_tree_view_button_press): do not try
+2001-12-13 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdialog.c, gtk/gtkrc.c, gtk/gtkwidget.c: Markup fixes.
+
Thu Dec 13 20:37:27 2001 Kristian Rietveld <kris@gtk.org>
* gtk/gtktreeview.c (gtk_tree_view_button_press): do not try
+2001-12-13 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdialog.c, gtk/gtkrc.c, gtk/gtkwidget.c: Markup fixes.
+
Thu Dec 13 20:37:27 2001 Kristian Rietveld <kris@gtk.org>
* gtk/gtktreeview.c (gtk_tree_view_button_press): do not try
+2001-12-13 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdialog.c, gtk/gtkrc.c, gtk/gtkwidget.c: Markup fixes.
+
Thu Dec 13 20:37:27 2001 Kristian Rietveld <kris@gtk.org>
* gtk/gtktreeview.c (gtk_tree_view_button_press): do not try
+2001-12-13 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdialog.c, gtk/gtkrc.c, gtk/gtkwidget.c: Markup fixes.
+
Thu Dec 13 20:37:27 2001 Kristian Rietveld <kris@gtk.org>
* gtk/gtktreeview.c (gtk_tree_view_button_press): do not try
+2001-12-13 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdialog.c, gtk/gtkrc.c, gtk/gtkwidget.c: Markup fixes.
+
Thu Dec 13 20:37:27 2001 Kristian Rietveld <kris@gtk.org>
* gtk/gtktreeview.c (gtk_tree_view_button_press): do not try
+2001-12-13 Matthias Clasen <matthiasc@poet.de>
+
+ * gdk-pixbuf/tmpl/scaling.sgml, gdk/tmpl/fonts.sgml,
+ gdk/tmpl/general.sgml, gdk/tmpl/rgb.sgml, gdk/tmpl/visuals.sgml,
+ gdk/tmpl/windows.sgml, gtk/gtk-docs.sgml, gtk/tmpl/gtkaccellabel.sgml,
+ gtk/tmpl/gtkcombo.sgml, gtk/tmpl/gtkdialog.sgml,
+ gtk/tmpl/gtkdrawingarea.sgml, gtk/tmpl/gtkeditable.sgml,
+ gtk/tmpl/gtkfilesel.sgml, gtk/tmpl/gtkfontseldlg.sgml,
+ gtk/tmpl/gtkimage.sgml, gtk/tmpl/gtkmain.sgml, gtk/tmpl/gtkmenu.sgml,
+ gtk/tmpl/gtkmessagedialog.sgml, gtk/tmpl/gtkobject.sgml,
+ gtk/tmpl/gtkpaned.sgml, gtk/tmpl/gtkradiobutton.sgml,
+ gtk/tmpl/gtkrc.sgml, gtk/tmpl/gtkscale.sgml, gtk/tmpl/gtksignal.sgml,
+ gtk/tmpl/gtksocket.sgml, gtk/tmpl/gtkspinbutton.sgml,
+ gtk/tmpl/gtktogglebutton.sgml, gtk/tmpl/gtksignal.sgml,
+ gtk/tmpl/gtktooltips.sgml, gtk/tmpl/gtkwindow.sgml,
+ gdk/tmpl/regions.sgml, gtk/tmpl/gtkfontsel.sgml,
+ gtk/tmpl/gtkpixmap.sgml, gtk/tmpl/gtkprogress.sgml,
+ gtk/tmpl/gtkselection.sgml, gtk/tmpl/gtktable.sgml,
+ gtk/tmpl/gtktipsquery.sgml: Markup fixes (mainly examples).
+
2001-12-12 Matthias Clasen <matthiasc@poet.de>
* gtk/tmpl/gtklist.sgml: Markup fixes.
as calling gdk_pixbuf_scale().
</para>
+ <example>
+ <title>Handling an expose event.</title>
<programlisting>
gboolean
expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
return TRUE;
}
</programlisting>
+ </example>
<!-- ##### SECTION See_Also ##### -->
<para>
- GdkRGB
+ <link linkend="gdk-GdkRGB">GdkRGB</link>.
</para>
<!-- ##### ENUM GdkInterpType ##### -->
consists of a sequence of fields separated (and surrounded by) '-'
characters. For example, Adobe Helvetica Bold 12 pt, has the
full description:
-
-<programlisting>
+<informalexample><programlisting>
"-adobe-helvetica-bold-r-normal--12-120-75-75-p-70-iso8859-1"
-</programlisting>
+</programlisting></informalexample>
</para>
<para>
'*' can be used as a wildcard to match any portion of
the XLFD. For instance, the above example could
also be specified as
-
-<programlisting>
+<informalexample><programlisting>
"-*-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1"
-</programlisting>
+</programlisting></informalexample>
It is generally a good idea to use wildcards for any
portion of the XLFD that your program does not care
See the X Session Management Library documentation for more information on
session management and the Inter-Client Communication Conventions Manual
(ICCCM) for information on the <literal>WM_CLIENT_LEADER</literal> property.
-(Both documents are part of the X Windows distribution.)
+(Both documents are part of the X Window System distribution.)
</para>
@sm_client_id: the client id assigned by the session manager when the
Exits the application using the <function>exit()</function> system call.
</para>
<para>
-This routine is provided mainly for backwards compatability, since it used to
+This routine is provided mainly for backwards compatibility, since it used to
perform tasks necessary to exit the application cleanly. Those tasks are now
performed in a function which is automatically called on exit (via the use
of g_atexit()).
<example>
<title>Trapping an X error.</title>
<programlisting>
- gdk_error_trap_push ();
+ gdk_error_trap_push (<!>);
/* ... Call the X function which may cause an error here ... */
/* Flush the X queue to catch errors now. */
- gdk_flush ();
+ gdk_flush (<!>);
- if (gdk_error_trap_pop ())
+ if (gdk_error_trap_pop (<!>))
{
/* ... Handle the error here ... */
}
@src1: a #GdkRectangle.
@src2: a #GdkRectangle.
@dest: the intersection of @src1 and @src2.
-@Returns: TRUE if the rectangles intersect.
+@Returns: %TRUE if the rectangles intersect.
<!-- ##### FUNCTION gdk_rectangle_union ##### -->
<!-- ##### FUNCTION gdk_region_empty ##### -->
<para>
-Returns TRUE if the #GdkRegion is empty.
+Returns %TRUE if the #GdkRegion is empty.
</para>
@region: a #GdkRegion.
-@Returns: TRUE if @region is empty.
+@Returns: %TRUE if @region is empty.
<!-- ##### FUNCTION gdk_region_equal ##### -->
<para>
-Returns TRUE if the two regions are the same.
+Returns %TRUE if the two regions are the same.
</para>
@region1: a #GdkRegion.
@region2: a #GdkRegion.
-@Returns: TRUE if @region1 and @region2 are equal.
+@Returns: %TRUE if @region1 and @region2 are equal.
<!-- ##### FUNCTION gdk_region_point_in ##### -->
<para>
-Returns TRUE if a point is in a region.
+Returns %TRUE if a point is in a region.
</para>
@region: a #GdkRegion.
@x: the x coordinate of a point.
@y: the y coordinate of a point.
-@Returns: TRUE if the point is in @region.
+@Returns: %TRUE if the point is in @region.
<!-- ##### FUNCTION gdk_region_rect_in ##### -->
@region: a #GdkRegion.
@rect: a #GdkRectangle.
-@Returns: GDK_OVERLAP_RECTANGLE_IN, GDK_OVERLAP_RECTANGLE_OUT, or
-GDK_OVERLAP_RECTANGLE_PART, depending on whether the rectangle is inside,
+@Returns: %GDK_OVERLAP_RECTANGLE_IN, %GDK_OVERLAP_RECTANGLE_OUT, or
+%GDK_OVERLAP_RECTANGLE_PART, depending on whether the rectangle is inside,
outside, or partly inside the #GdkRegion, respectively.
<!-- ##### SECTION Long_Description ##### -->
<para>
-GdkRgb is a low-level module which renders RGB, grayscale, and indexed
+GdkRGB is a low-level module which renders RGB, grayscale, and indexed
colormap images to a #GdkDrawable. It does this as efficiently as
possible, handling issues such as colormaps, visuals, dithering,
temporary buffers, and so on. Most code should use the higher-level
set the threshold for installing colormaps with
gdk_rgb_set_min_colors(). The default is 5x5x5 (125). If a colorcube
of this size or larger can be allocated in the default colormap, then
-that's done. Otherwise, GdkRgb creates its own private colormap.
+that's done. Otherwise, GdkRGB creates its own private colormap.
Setting it to 0 means that it always tries to use the default
colormap, and setting it to 216 means that it always creates a private
one if it cannot allocate the 6x6x6 colormap in the default. If you
always want a private colormap (to avoid consuming too many colormap
-entries for other apps, say), you can use gdk_rgb_set_install(TRUE).
+entries for other apps, say), you can use
+<literal>gdk_rgb_set_install(TRUE)</literal>.
Setting the value greater than 216 exercises a bug in older versions
-of GdkRgb. Note, however, that setting it to 0 doesn't let you get
+of GdkRGB. Note, however, that setting it to 0 doesn't let you get
away with ignoring the colormap and visual - a colormap is always
created in grayscale and direct color modes, and the visual is changed
in cases where a "better" visual than the default is available.
gtk_init (&argc, &argv);
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
- darea = gtk_drawing_area_new ();
+ darea = gtk_drawing_area_new (<!>);
gtk_widget_set_size_request (darea, IMAGE_WIDTH, IMAGE_HEIGHT);
gtk_container_add (GTK_CONTAINER (window), darea);
gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
}
}
- gtk_main ();
+ gtk_main (<!>);
return 0;
}
<varlistentry>
<term>#GdkColor</term>
-<listitem><para>The underlying Gdk mechanism for allocating
+<listitem><para>The underlying GDK mechanism for allocating
colors.</para></listitem>
</varlistentry>
<!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
<para>
-Draws an RGB image in the drawable. This is the core GdkRgb
+Draws an RGB image in the drawable. This is the core GdkRGB
function, and likely the only one you will need to use.
</para>
</para>
@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
-@gc: The graphics context (all Gdk drawing operations require one; its
+@gc: The graphics context (all GDK drawing operations require one; its
contents are ignored).
@x: The x coordinate of the top-left corner in the drawable.
@y: The y coordinate of the top-left corner in the drawable.
<!-- ##### ENUM GdkRgbDither ##### -->
<para>
-
-Selects whether or not GdkRgb applies dithering
+Selects whether or not GdkRGB applies dithering
to the image on display. There are three values:
</para>
</itemizedlist>
<para>
-Since GdkRgb currently only handles images with 8 bits per component,
+Since GdkRGB currently only handles images with 8 bits per component,
dithering on 24 bit per pixel displays is a moot point.
</para>
<!-- ##### FUNCTION gdk_rgb_set_install ##### -->
<para>
-If @install is TRUE, directs GdkRgb to always install a new "private"
+If @install is %TRUE, directs GdkRGB to always install a new "private"
colormap rather than trying to find a best fit with the colors already
-allocated. Ordinarily, GdkRgb will install a colormap only if a
+allocated. Ordinarily, GdkRGB will install a colormap only if a
sufficient cube cannot be allocated.
</para>
but also leads to the dreaded "colormap flashing" effect.
</para>
-@install: TRUE to set install mode.
+@install: %TRUE to set install mode.
<!-- ##### FUNCTION gdk_rgb_set_min_colors ##### -->
<para>
Sets the minimum number of colors for the color cube. Generally,
-GdkRgb tries to allocate the largest color cube it can. If it can't
+GdkRGB tries to allocate the largest color cube it can. If it can't
allocate a color cube at least as large as @min_colors, it installs a
private colormap.
</para>
<!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
<para>
-Gets a "preferred visual" chosen by GdkRgb. In previous versions of
-GDK, this was the only visual GdkRgb could use for rendering. In
-current versions, it's simply the visual GdkRgb would have chosen as
-the optimal one in those previous versions. GdkRgb can now render to
+Gets a "preferred visual" chosen by GdkRGB. In previous versions of
+GDK, this was the only visual GdkRGB could use for rendering. In
+current versions, it's simply the visual GdkRGB would have chosen as
+the optimal one in those previous versions. GdkRGB can now render to
drawables with any visual.
</para>
-@Returns: The #GdkVisual chosen by GdkRgb.
+@Returns: The #GdkVisual chosen by GdkRGB.
<!-- ##### FUNCTION gdk_rgb_get_colormap ##### -->
<!-- ##### MACRO gdk_rgb_get_cmap ##### -->
<para>
-Gets the colormap set by GdkRgb. This colormap and the corresponding
-visual should be used when creating windows that will be drawn in by GdkRgb.
+Gets the colormap set by GdkRGB. This colormap and the corresponding
+visual should be used when creating windows that will be drawn in by GdkRGB.
</para>
-@Returns: The #GdkColormap set by GdkRgb.
+@Returns: The #GdkColormap set by GdkRGB.
<!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
<para>
-Determine whether the visual is ditherable. This function may be
+Determines whether the visual is ditherable. This function may be
useful for presenting a user interface choice to the user about which
dither mode is desired; if the display is not ditherable, it may make
sense to gray out or hide the corresponding UI widget.
</para>
-@Returns: TRUE if the visual is ditherable.
+@Returns: %TRUE if the visual is ditherable.
<!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
Sets the "verbose" flag. This is generally only useful for debugging.
</para>
-@verbose: TRUE if verbose messages are desired.
+@verbose: %TRUE if verbose messages are desired.
a particular visual.
</para>
-<figure float="1" id="rgbmask">
+<example id="rgbmask">
<title>Constructing a pixel value from components</title>
<programlisting>
guint
((r >> (16 - visual->blue_prec)) << visual->blue_shift);
}
</programlisting>
-</figure>
+</example>
@parent_instance: inherited portion from #GObject
@type: The type of this visual.
<para>
Here's an example of how the terminal example would be implemented, assuming
a terminal area widget called "terminal" and a toplevel window "toplevel":
-<programlisting>
+<informalexample><programlisting>
GdkGeometry hints;
hints.base_width = terminal->char_width;
GDK_HINT_RESIZE_INC |
GDK_HINT_MIN_SIZE |
GDK_HINT_BASE_SIZE);
-</programlisting>
+</programlisting></informalexample>
</para>
<para>
<!entity % local.notation.class "| PNG">
<!entity hash "#">
-<!entity empty "">
<!entity GtkAccelLabel SYSTEM "sgml/gtkaccellabel.sgml">
<!entity GtkAdjustment SYSTEM "sgml/gtkadjustment.sgml">
<!entity GtkAlignment SYSTEM "sgml/gtkalignment.sgml">
GtkAccelGroup *accel_group;
/* Create a #GtkAccelGroup and add it to the window. */
- accel_group = gtk_accel_group_new ();
+ accel_group = gtk_accel_group_new (<!>);
gtk_window_add_accel_group (GTK_WINDOW (window), accel_group);
/* Create the menu item using the convenience function. */
gtk_widget_show (save_item);
gtk_container_add (GTK_CONTAINER (menu), save_item);
- /* Now add the accelerator to the #GtkMenuItem. Note that since we called
- gtk_menu_item_new_with_label() to create the #GtkMenuItem the
- #GtkAccelLabel is automatically set up to display the #GtkMenuItem
+ /* Now add the accelerator to the GtkMenuItem. Note that since we called
+ gtk_menu_item_new_with_label(<!>) to create the GtkMenuItem the
+ GtkAccelLabel is automatically set up to display the GtkMenuItem
accelerators. We just need to make sure we use GTK_ACCEL_VISIBLE here. */
gtk_widget_add_accelerator (save_item, "activate", accel_group,
GDK_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
</para>
<example id="gtkcombo-simple-example">
-<title>Creating a #GtkCombo widget with simple text items.</title>
+<title>Creating a <structname>GtkCombo</structname> widget with simple text
+items.</title>
<programlisting>
GtkWidget *combo;
GList *items = NULL;
items = g_list_append (items, "Fourth Item");
items = g_list_append (items, "Fifth Item");
- combo = gtk_combo_new ();
+ combo = gtk_combo_new (<!>);
gtk_combo_set_popdown_strings (GTK_COMBO (combo), items);
</programlisting>
</example>
<example>
-<title>Creating a #GtkCombo widget with a complex item.</title>
+<title>Creating a <structname>GtkCombo</structname> widget with a complex item.</title>
<programlisting>
GtkWidget *combo, *item, *hbox, *arrow, *label;
- combo = gtk_combo_new ();
+ combo = gtk_combo_new (<!>);
- item = gtk_list_item_new ();
+ item = gtk_list_item_new (<!>);
gtk_widget_show (item);
/* You can put almost anything into the GtkListItem widget. Here we will use
</para>
<para>
-Gtk+ treats a dialog as a window split vertically. The top section is a
+GTK+ treats a dialog as a window split vertically. The top section is a
#GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry should
be packed. The bottom area is known as the
<structfield>action_area</structfield>. This is generally used for
<para>
If 'dialog' is a newly created dialog, the two primary areas of the window
-can be accessed as GTK_DIALOG(dialog)->vbox and GTK_DIALOG(dialog)->action_area,
+can be accessed as <literal>GTK_DIALOG(dialog)->vbox</literal> and
+<literal>GTK_DIALOG(dialog)->action_area</literal>,
as can be seen from the example, below.
</para>
user input), can be created by calling gtk_window_set_modal() on the dialog. Use
the GTK_WINDOW() macro to cast the widget returned from gtk_dialog_new() into a
#GtkWindow. When using gtk_dialog_new_with_buttons() you can also pass the
-GTK_DIALOG_MODAL flag to make a dialog modal.
+#GTK_DIALOG_MODAL flag to make a dialog modal.
</para>
<para>
meaning to positive response IDs; these are entirely user-defined. But for
convenience, you can use the response IDs in the #GtkResponseType enumeration
(these all have values less than zero). If a dialog receives a delete event, the
-"response" signal will be emitted with a response ID of GTK_RESPONSE_NONE.
+"response" signal will be emitted with a response ID of #GTK_RESPONSE_NONE.
</para>
#GtkMessageDialog to save yourself some effort. But you'd need to create the
dialog contents manually if you had more than a simple message in the dialog.
<example>
-<title>Simple #GtkDialog usage.</title>
+<title>Simple <structname>GtkDialog</structname> usage.</title>
<programlisting>
/* Function to open a dialog box displaying the message provided. */
-void quick_message(#gchar *message) {
+void quick_message (gchar *message) {
- #GtkWidget *dialog, *label;
+ GtkWidget *dialog, *label;
/* Create the widgets */
<!-- ##### FUNCTION gtk_dialog_new ##### -->
<para>
Creates a new dialog box. Widgets should not be packed into this #GtkWindow
-directly, but into the vbox and action_area, as described above.
+directly, but into the @vbox and @action_area, as described above.
</para>
@Returns: a new #GtkDialog.
<para>
Emitted when an action widget is clicked, the dialog receives a delete event, or
the application programmer calls gtk_dialog_response(). On a delete event, the
-response ID is GTK_RESPONSE_NONE. Otherwise, it depends on which action widget
+response ID is #GTK_RESPONSE_NONE. Otherwise, it depends on which action widget
was clicked.
</para>
draw only the pixels within the requested area and
should draw or clear all these pixels.
</para>
+<example>
+<title>Simple <structname>GtkDrawingArea</structname> usage.</title>
<programlisting>
gboolean
expose_event (GdkWidget *widget, GdkEventExpose *event, gpointer data)
return TRUE;
}
[...]
- GtkWidget *drawing_area = gtk_drawing_area_new ();
+ GtkWidget *drawing_area = gtk_drawing_area_new (<!>);
gtk_drawing_area_size (GTK_DRAWING_AREA (drawing_area),
100, 100);
gtk_signal_connect (GTK_OBJECT (drawing_area),
</programlisting>
+</example>
<!-- ##### SECTION See_Also ##### -->
<para>
<!-- ##### STRUCT GtkDrawingArea ##### -->
<para>
-The #GtkDrawingArea-struct struct contains private data only, and
+The #GtkDrawingArea struct contains private data only, and
should be accessed using the functions below.
</para>
<!-- ##### FUNCTION gtk_drawing_area_new ##### -->
<para>
-Create a new drawing area.
+Creates a new drawing area.
</para>
@Returns: a new #GtkDrawingArea
<!-- ##### FUNCTION gtk_drawing_area_size ##### -->
<para>
-Set the size that the drawing area will request
+Sets the size that the drawing area will request
in response to a "size_request" signal. The
drawing area may actually be allocated a size
larger than this depending on how it is packed
can convert all entry into a widget into uppercase.
<example>
-<title> Forcing entry to uppercase </title>
+<title>Forcing entry to uppercase.</title>
<programlisting>
#include <ctype.h>
int i;
gchar *result = g_new (gchar, length);
- for (i=0; i<length; i++)
- result[i] = islower(text[i]) ? toupper(text[i]) : text[i];
+ for (i = 0; i < length; i++)
+ result[i] = islower (text[i]) ? toupper (text[i]) : text[i];
gtk_signal_handler_block_by_func (GTK_OBJECT (editable),
GTK_SIGNAL_FUNC (insert_text_handler),
<!-- ##### FUNCTION gtk_editable_insert_text ##### -->
<para>
-Insert text at a given position.
+Inserts text at a given position.
</para>
@editable: a #GtkEditable widget.
<!-- ##### FUNCTION gtk_editable_delete_text ##### -->
<para>
-Delete a sequence of characters. The characters that
+Deletes a sequence of characters. The characters that
are deleted are those characters at positions from
@start_pos up to, but not including @end_pos. If
@end_pos is negative, then the the characters deleted
<!-- ##### SECTION Long_Description ##### -->
<para>
-GtkFileSelection should be used to retrieve file or directory names from the user. It will create a new dialog window containing a directory list, and a file list corresponding to the current working directory. The filesystem can be navigated using the directory list or the drop-down history menu. Alternatively, the TAB key can be used to navigate using filename completion - common in text based editors such as emacs and jed.
+#GtkFileSelection should be used to retrieve file or directory names from
+the user. It will create a new dialog window containing a directory list,
+and a file list corresponding to the current working directory. The filesystem
+can be navigated using the directory list or the drop-down history menu.
+Alternatively, the TAB key can be used to navigate using filename
+completion - common in text based editors such as emacs and jed.
</para>
<para>
File selection dialogs are created with a call to gtk_file_selection_new().
</para>
<para>
<example>
-<title>Getting a filename from the user</title>
+<title>Getting a filename from the user.</title>
<programlisting>
/* The file selection widget and the string to store the chosen filename */
GtkWidget *file_selector;
gchar *selected_filename;
-void store_filename(GtkFileSelection *selector, gpointer user_data) {
- selected_filename = gtk_file_selection_get_filename (GTK_FILE_SELECTION(file_selector));
+void store_filename (GtkFileSelection *selector, gpointer user_data) {
+ selected_filename = gtk_file_selection_get_filename (GTK_FILE_SELECTION (file_selector));
}
-void create_file_selection(void) {
+void create_file_selection (void) {
/* Create the selector */
- file_selector = gtk_file_selection_new("Please select a file for editing.");
+ file_selector = gtk_file_selection_new ("Please select a file for editing.");
- gtk_signal_connect (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->ok_button),
+ gtk_signal_connect (GTK_OBJECT (GTK_FILE_SELECTION (file_selector)->ok_button),
"clicked", GTK_SIGNAL_FUNC (store_filename), NULL);
/* Ensure that the dialog box is destroyed when the user clicks a button. */
- gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->ok_button),
+ gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION (file_selector)->ok_button),
"clicked", GTK_SIGNAL_FUNC (gtk_widget_destroy),
(gpointer) file_selector);
- gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->cancel_button),
+ gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION (file_selector)->cancel_button),
"clicked", GTK_SIGNAL_FUNC (gtk_widget_destroy),
(gpointer) file_selector);
@fontsel: a #GtkFontSelection.
@fontname: a fontname.
-@Returns: TRUE if the font was found.
+@Returns: %TRUE if the font was found.
<!-- ##### FUNCTION gtk_font_selection_get_preview_text ##### -->
</para>
@fsd: a #GtkFontSelectionDialog.
-@Returns: the currently-selected font, or NULL if no font is selected.
+@Returns: the currently-selected font, or %NULL if no font is selected.
<!-- ##### FUNCTION gtk_font_selection_dialog_get_font_name ##### -->
</para>
@fsd: a #GtkFontSelectionDialog.
-@Returns: the currently-selected font name, or NULL if no font is selected.
+@Returns: the currently-selected font name, or %NULL if no font is selected.
<!-- ##### FUNCTION gtk_font_selection_dialog_set_font_name ##### -->
@fsd: a #GtkFontSelectionDialog.
@fontname: a fontname.
-@Returns: TRUE if the font was found.
+@Returns: %TRUE if the font was found.
<!-- ##### FUNCTION gtk_font_selection_dialog_get_preview_text ##### -->
#GdkPixbuf ("pixel buffer") from a file, and then display that.
There's a convenience function to do this, gtk_image_new_from_file(),
used as follows:
-<programlisting>
+<informalexample><programlisting>
GtkWidget *image;
image = gtk_image_new_from_file ("myfile.png");
-</programlisting>
+</programlisting></informalexample>
If the file isn't loaded successfully, the image will contain a
"broken image" icon similar to that used in many web browsers.
If you want to handle errors in loading the file yourself,
so by default does not receive events. If you want to receive events
on the image, such as button clicks, place the image inside a
#GtkEventBox, then connect to the event signals on the event box.
-For example, here is some code that handles button press events
-on a #GtkImage:
+<example>
+<title>Handling button press events on a
+<structname>GtkImage</structname>.</title>
<programlisting>
static void
button_press_callback (GtkWidget *event_box,
image = gtk_image_new_from_file ("myfile.png");
- event_box = gtk_event_box_new ();
+ event_box = gtk_event_box_new (<!>);
gtk_container_add (GTK_CONTAINER (event_box), image);
return image;
}
</programlisting>
+</example>
</para>
<para>
When handling events on the event box, keep in mind that coordinates
<!-- ##### FUNCTION gtk_image_new ##### -->
<para>
-Creates the new GtkImage using the value and the mask.
+Creates the new #GtkImage using the value and the mask.
</para>
-@Returns: the GtkImage
+@Returns: the #GtkImage
<!-- # Unused Parameters # -->
@val:
-@mask: a GDKBitmap that indicates which parts of the image should be transparent.
+@mask: a #GdkBitmap that indicates which parts of the image should be transparent.
<!-- ##### FUNCTION gtk_image_set ##### -->
<para>
-Sets the GtkImage
+Sets the #GtkImage.
</para>
@image: a #GdkPixmap
@val:
-@mask: a GDKBitmap that indicates which parts of the image should be transparent.
+@mask: a #GdkBitmap that indicates which parts of the image should be transparent.
<!-- ##### FUNCTION gtk_image_get ##### -->
<para>
-Gets the GtkImage
+Gets the #GtkImage.
</para>
@image: a #GdkPixmap
@val:
-@mask: a GDKBitmap that indicates which parts of the image should be transparent.
+@mask: a #GdkBitmap that indicates which parts of the image should be transparent.
<!-- ##### ARG GtkImage:pixbuf ##### -->
</para>
<example>
-<title>Typical <function>main</function> function for a GTK application</title>
+<title>Typical <function>main</function> function for a GTK+ application</title>
<programlisting>
int
main (int argc, char **argv)
{
/* Initialize i18n support */
- gtk_set_locale (∅);
+ gtk_set_locale (<!>);
/* Initialize the widget set */
gtk_init (&argc, &argv);
gtk_widget_show_all (mainwin);
/* Enter the main event loop, and wait for user interaction */
- gtk_main (∅);
+ gtk_main (<!>);
/* The user lost interest */
return 0;
<!-- ##### FUNCTION gtk_init ##### -->
<para>
-Call this function before using any other GTK functions in your GUI
+Call this function before using any other GTK+ functions in your GUI
applications. It will initialize everything needed to operate the toolkit and
parses some standard command line options. <parameter>argc</parameter> and
<parameter>argv</parameter> are adjusted accordingly so your own code will
<para>
This function will terminate your program if it was unable to initialize
the GUI for some reason. If you want your program to fall back to a
-textual interface you want to call <function>gtk_init_check</function>
-instead.
+textual interface you want to call gtk_init_check() instead.
</para>
</note>
<para>
Terminates the program and returns the given exit code to the caller.
This function will shut down the GUI and free all resources allocated
-for GTK.
+for GTK+.
</para>
@error_code: Return value to pass to the caller. This is dependend on the
</para>
<example>
-<title>Updating the GUI during a long computation</title>
+<title>Updating the GUI during a long computation.</title>
<programlisting>
/* computation going on */
...
- while (gtk_events_pending (∅))
- gtk_main_iteration (∅);
+ while (gtk_events_pending (<!>))
+ gtk_main_iteration (<!>);
...
/* computation continued */
</programlisting>
gtk_container_add (GTK_CONTAINER (win), but);
gtk_widget_show_all (win);
- gtk_main (∅);
+ gtk_main (<!>);
return 0;
}
</programlisting>
<title>Connecting the popup signal handler.</title>
<programlisting>
/* connect our handler which will popup the menu */
- gtk_signal_connect_object(GTK_OBJECT(window), "button_press_event",
- GTK_SIGNAL_FUNC (my_popup_handler), GTK_OBJECT(menu));
+ gtk_signal_connect_object (GTK_OBJECT (window), "button_press_event",
+ GTK_SIGNAL_FUNC (my_popup_handler), GTK_OBJECT (menu));
</programlisting>
</example>
<title>Signal handler which displays a popup menu.</title>
<programlisting>
static gint
-my_popup_handler(GtkWidget *widget, GdkEvent *event)
+my_popup_handler (GtkWidget *widget, GdkEvent *event)
{
GtkMenu *menu;
GdkEventButton *event_button;
<!-- ##### STRUCT GtkMenu ##### -->
<para>
-The #GtkMenu-struct struct contains private data only, and
+The #GtkMenu struct contains private data only, and
should be accessed using the functions below.
</para>
<para>
Displays a menu and makes it available for selection. Applications can use
this function to display context-sensitive menus, and will typically supply
-NULL for the @parent_menu_shell, @parent_menu_item, @func and @data
+%NULL for the @parent_menu_shell, @parent_menu_item, @func and @data
parameters. The default menu positioning function will position the menu
at the current pointer position.
</para>
</para>
@menu: a #GtkMenu.
-@torn_off: If TRUE, menu is displayed as a tearoff menu.
+@torn_off: If %TRUE, menu is displayed as a tearoff menu.
<!-- ##### FUNCTION gtk_menu_attach_to_widget ##### -->
<para>
The easiest way to do a modal message dialog is to use gtk_dialog_run(), though
-you can also pass in the GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically
+you can also pass in the %GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically
makes the dialog modal and waits for the user to respond to it. gtk_dialog_run()
returns when any dialog button is clicked.
<example>
-<title>Modal #GtkMessageDialog</title>
+<title>A modal dialog.</title>
<programlisting>
dialog = gtk_message_dialog_new (main_application_window,
GTK_DIALOG_DESTROY_WITH_PARENT,
<para>
You might do a non-modal #GtkMessageDialog as follows:
<example>
-<title>Non-modal #GtkMessageDialog</title>
+<title>A non-modal dialog.</title>
<programlisting>
dialog = gtk_message_dialog_new (main_application_window,
GTK_DIALOG_DESTROY_WITH_PARENT,
<!-- ##### ENUM GtkButtonsType ##### -->
<para>
Prebuilt sets of buttons for the dialog. If
-none of these choices are appropriate, simply use GTK_BUTTONS_NONE
+none of these choices are appropriate, simply use %GTK_BUTTONS_NONE
then call gtk_dialog_add_buttons().
</para>
GtkObject
<!-- ##### SECTION Short_Description ##### -->
-The base class of the Gtk type hierarchy.
+The base class of the GTK+ type hierarchy.
<!-- ##### SECTION Long_Description ##### -->
<refsect2>
<para>
When you add a widget to its parent container, the parent container
will do this:
-<programlisting>
+<informalexample><programlisting>
g_object_ref (G_OBJECT (child_widget));
gtk_object_sink (GTK_OBJECT (child_widget));
-</programlisting>
+</programlisting></informalexample>
This means that the container now owns a reference to the child widget (since
it called g_object_ref()), and the child widget has no floating reference.
</para>
<para>
The purpose of the floating reference is to keep the child widget alive
until you add it to a parent container:
-<programlisting>
- button = gtk_button_new ();
+<informalexample><programlisting>
+ button = gtk_button_new (<!>);
/* button has one floating reference to keep it alive */
gtk_container_add (GTK_CONTAINER (container), button);
/* button has one non-floating reference owned by the container */
-</programlisting>
+</programlisting></informalexample>
</para>
<para>
#GtkWindow is a special case, because GTK+ itself will ref/sink it on creation.
<para>
<informalexample>
<programlisting>
-void set_box_properties(GtkBox* box)
+void set_box_properties (GtkBox* box)
{
- gtk_object_set(GTK_OBJECT(box), "homogeneous", TRUE,
- "spacing", 8,
- NULL);
+ gtk_object_set (GTK_OBJECT (box), "homogeneous", TRUE,
+ "spacing", 8,
+ NULL);
}
</programlisting>
</informalexample>
This function is equivalent to:
<informalexample>
<programlisting>
- gtk_object_set_data(object, "user_data", data);
+ gtk_object_set_data (object, "user_data", data);
</programlisting>
</informalexample>
</para>
<!-- ##### SECTION Long_Description ##### -->
<para>
-GtkPaned is the base class for widgets with two panes,
+#GtkPaned is the base class for widgets with two panes,
arranged either horizontally (#GtkHPaned) or
vertically (#GtkVPaned). Child widgets are
added to the panes of the widget with
can drag to adjust the division. It does not
draw any relief around the children or around
the separator. (The space in which the separator
-is called the gutter). Often, it is useful
+is called the gutter.) Often, it is useful
to put each child inside a #GtkFrame with the
shadow type set to %GTK_SHADOW_IN so that the
gutter appears as a ridge.
or shrink along with the paned widget. If @shrink
is true, then when that child can be made smaller
than it's requisition by the user. Setting @shrink
-to FALSE allows the application to set a minimum
+to %FALSE allows the application to set a minimum
size. If @resize is false for both children, then
this is treated as if @resize is true for both
children.
</para>
<example>
-<title> Creating a paned widget with minimum sizes </title>
+<title>Creating a paned widget with minimum sizes.</title>
<programlisting>
-GtkWidget *hpaned = gtk_hpaned_new();
-GtkWidget *frame1 = gtk_frame_new(NULL);
-GtkWidget *frame2 = gtk_frame_new(NULL);
+GtkWidget *hpaned = gtk_hpaned_new (<!>);
+GtkWidget *frame1 = gtk_frame_new (NULL);
+GtkWidget *frame2 = gtk_frame_new (NULL);
gtk_frame_set_shadow_type (GTK_FRAME (frame1), GTK_SHADOW_IN);
gtk_frame_set_shadow_type (GTK_FRAME (frame2), GTK_SHADOW_IN);
<!-- ##### FUNCTION gtk_paned_add1 ##### -->
<para>
-Add a child to the top or left pane with
+Adds a child to the top or left pane with
default parameters. This is equivalent
-to
-<programlisting>
-gtk_paned_pack1(paned, child, FALSE, TRUE);
-</programlisting>
+to <literal>gtk_paned_pack1 (paned, child, FALSE, TRUE)</literal>.
</para>
@paned: a paned widget
<!-- ##### FUNCTION gtk_paned_add2 ##### -->
<para>
-Add a child to the bottom or right pane with default
+Adds a child to the bottom or right pane with default
parameters. This is equivalent to
-<programlisting>
-gtk_paned_pack2(paned, child, TRUE, TRUE);
-</programlisting>
+<literal>gtk_paned_pack2(paned, child, TRUE, TRUE)</literal>.
</para>
@paned: a paned widget
<!-- ##### MACRO gtk_paned_handle_size ##### -->
<para>
-Old name for gtk_paned_set_handle_size()
+Old name for gtk_paned_set_handle_size().
</para>
<!-- ##### MACRO gtk_paned_gutter_size ##### -->
<para>
-Old name for gtk_paned_set_gutter_size()
+Old name for gtk_paned_set_gutter_size().
</para>
@p:
<!-- ##### FUNCTION gtk_paned_pack1 ##### -->
<para>
-Add a child to the top or left pane.
+Adds a child to the top or left pane.
</para>
@paned: a paned widget
<!-- ##### FUNCTION gtk_paned_pack2 ##### -->
<para>
-Add a child to the bottom or right pane.
+Adds a child to the bottom or right pane.
</para>
@paned: a paned widget
<!-- ##### MACRO gtk_paned_set_gutter_size ##### -->
<para>
-In older versions of Gtk, this function used to set the width of the
+In older versions of GTK+, this function used to set the width of the
gutter (the area between the two panes). It does nothing now.
</para>
</para>
@pixmap: a #GtkPixmap.
-@build: set to TRUE if an extra pixmap should be automatically created to use
+@build: set to %TRUE if an extra pixmap should be automatically created to use
when the pixmap is insensitive.
</para>
@progress: a #GtkProgress.
-@activity_mode: a boolean, TRUE for activity mode.
+@activity_mode: a boolean, %TRUE for activity mode.
<!-- ##### FUNCTION gtk_progress_get_current_text ##### -->
<title>How to create a group of two radio buttons.</title>
<programlisting>
-void create_radio_buttons(void) {
+void create_radio_buttons (void) {
GtkWidget *window, *radio1, *radio2, *box, *entry;
- window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
- box = gtk_vbox_new(TRUE, 2);
+ window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
+ box = gtk_vbox_new (TRUE, 2);
- /* Create a radio button with a #GtkEntry widget */
- radio1 = gtk_radio_button_new(NULL);
- entry = gtk_entry_new();
- gtk_container_add(GTK_CONTAINER(radio1), entry);
+ /* Create a radio button with a GtkEntry widget */
+ radio1 = gtk_radio_button_new (NULL);
+ entry = gtk_entry_new (<!>);
+ gtk_container_add (GTK_CONTAINER (radio1), entry);
/* Create a radio button with a label */
- radio2 = gtk_radio_button_new_with_label_from_widget (GTK_RADIO_BUTTON(radio1),
+ radio2 = gtk_radio_button_new_with_label_from_widget (GTK_RADIO_BUTTON (radio1),
"I'm the second radio button.");
/* Pack them into a box, then show all the widgets */
gtk_box_pack_start (GTK_BOX (box), radio1, TRUE, TRUE, 2);
- gtk_box_pack_start(GTK_BOX(box), radio2, TRUE, TRUE, 2);
- gtk_container_add(GTK_CONTAINER(window), box);
+ gtk_box_pack_start (GTK_BOX (box), radio2, TRUE, TRUE, 2);
+ gtk_container_add (GTK_CONTAINER (window), box);
gtk_widget_show_all (window);
return;
}
then be packed into the radio button.
</para>
-@group: an existing radio button group, or NULL if you are creating a new group.
+@group: an existing radio button group, or %NULL if you are creating a new group.
@Returns: a new radio button.
Creates a new #GtkRadioButton with a text label.
</para>
-@group: an existing radio button group, or NULL if you are creating a new
+@group: an existing radio button group, or %NULL if you are creating a new
group.
@label: the text label to display next to the radio button.
@Returns: a new radio button.
by the <literal>widget</literal>, <literal>widget_class</literal>,
and <literal>class</literal> declarations. As an example
of such a statement:
-<programlisting>
+<informalexample><programlisting>
widget "mywindow.*.GtkEntry" style "my-entry-class"
-</programlisting>
+</programlisting></informalexample>
attaches the style <literal>"my-entry-class"</literal>
to all widgets whose <firstterm>widget class</firstterm>
matches the <firstterm>pattern</firstterm>
zero or more of any character. The three types of
matching are against the widget path, the
<firstterm>class path</firstterm> and the class
-heirarchy. Both the widget and the class paths consists of a
+hierarchy. Both the widget and the class paths consists of a
<literal>"."</literal> separated list of all the
parents of the widget and the widget itself from
outermost to innermost. The difference is that in
So, if you have a <classname>GtkEntry</classname> named
<literal>"myentry"</literal>, inside of a of a window
named <literal>"mywindow"</literal>, then the
-widget path is:
-<programlisting>
-"mwindow.GtkHBox.myentry"
-</programlisting>
-while the class path is:
-<programlisting>
-"GtkWindow.GtkHBox.GtkEntry"
-</programlisting>
+widget path is: <literal>"mwindow.GtkHBox.myentry"</literal>
+while the class path is: <literal>"GtkWindow.GtkHBox.GtkEntry"</literal>.
</para>
<para>
Matching against class is a little different. The pattern
match is done against all class names in the widgets
-class heirarchy (not the layout heirarchy) in sequence, so the
+class hierarchy (not the layout hierarchy) in sequence, so the
pattern:
-<programlisting>
+<informalexample><programlisting>
class "GtkButton" style "my-style"
-</programlisting>
+</programlisting></informalexample>
will match not just <classname>GtkButton</classname> widgets,
but also <classname>GtkToggleButton</classname> and
<classname>GtkCheckButton</classname> widgets, since
<replaceable>name</replaceable></literal></term>
<listitem>
<para>Specify a style or binding set for a particular
- branch of the inheritance heirarchy.</para>
+ branch of the inheritance hierarchy.</para>
</listitem>
</varlistentry>
<varlistentry>
wildcard, and if direction/state/size are omitted they default to
<literal>*</literal>. So for example, the following specifies different icons to
use for left-to-right and right-to-left languages:
-<programlisting>
+<informalexample><programlisting>
stock["my-stock-item"] =
{
{ "itemltr.png", LTR, *, * },
{ "itemrtl.png", RTL, *, * }
}
-</programlisting>
+</programlisting></informalexample>
This could be abbreviated as follows:
-<programlisting>
+<informalexample><programlisting>
stock["my-stock-item"] =
{
{ "itemltr.png", LTR },
{ "itemrtl.png", RTL }
}
-</programlisting>
+</programlisting></informalexample>
</para>
<para>
You can specify custom icons for specific sizes, as follows:
-<programlisting>
+<informalexample><programlisting>
stock["my-stock-item"] =
{
{ "itemmenusize.png", *, *, "gtk-menu" },
{ "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }
{ "itemgeneric.png" } /* implicit *, *, * as a fallback */
}
-</programlisting>
+</programlisting></informalexample>
The sizes that come with GTK+ itself are <literal>"gtk-menu"</literal>,
<literal>"gtk-small-toolbar"</literal>, <literal>"gtk-large-toolbar"</literal>,
<literal>"gtk-button"</literal>, <literal>"gtk-dialog"</literal>. Applications
<para>
It's also possible to use custom icons for a given state, for example:
-<programlisting>
+<informalexample><programlisting>
stock["my-stock-item"] =
{
{ "itemprelight.png", *, PRELIGHT },
{ "iteminsensitive.png", *, INSENSITIVE },
{ "itemgeneric.png" } /* implicit *, *, * as a fallback */
}
-</programlisting>
+</programlisting></informalexample>
</para>
<para>
set declaration is:
</para>
-<programlisting>
+<informalexample><programlisting>
binding <replaceable>name</replaceable> {
bind <replaceable>key</replaceable> {
<replaceable>signalname</replaceable> (<replaceable>param</replaceable>, ...)
}
...
}
-</programlisting>
+</programlisting></informalexample>
<para>
<replaceable>key</replaceable> is a string consisting of a
<!-- ##### FUNCTION gtk_rc_add_widget_name_style ##### -->
<para>
-Add a RcStyle that will be looked up by a match against
+Adds a RcStyle that will be looked up by a match against
the widget's pathname. This is equivalent to a:
-<programlisting>
+<literal>
widget PATTERN style STYLE
-</programlisting>
+</literal>
statement in a RC file.
</para>
<!-- ##### FUNCTION gtk_rc_add_widget_class_style ##### -->
<para>
-Add a RcStyle that will be looked up by a match against
+Adds a RcStyle that will be looked up by a match against
the widget's class pathname. This is equivalent to a:
-
-<programlisting>
+<literal>
widget_class PATTERN style STYLE
-</programlisting>
+</literal>
statement in a RC file.
</para>
<!-- ##### FUNCTION gtk_rc_add_class_style ##### -->
<para>
-Add a RcStyle that will be looked up by a matching against
-the class heirarchy of the widget. This is equivalent to a:
-<programlisting>
+Adds a RcStyle that will be looked up by a matching against
+the class hierarchy of the widget. This is equivalent to a:
+<literal>
class PATTERN style STYLE
-</programlisting>
+</literal>
statement in a RC file.
</para>
<!-- ##### FUNCTION gtk_rc_parse ##### -->
<para>
-Parse a given resource file.
+Parses a given resource file.
</para>
@filename: the filename of a file to parse.
<!-- ##### FUNCTION gtk_rc_parse_string ##### -->
<para>
-Parse resource information directly from a string.
+Parses resource information directly from a string.
</para>
@rc_string: a string to parse.
<!-- ##### FUNCTION gtk_rc_style_new ##### -->
<para>
-Create a new #GtkRcStyle with no fields set and
+Creates a new #GtkRcStyle with no fields set and
a reference count of 1.
</para>
-@Returns: the newly create #GtkRcStyle
+@Returns: the newly-created #GtkRcStyle
<!-- ##### FUNCTION gtk_rc_style_copy ##### -->
<!-- ##### FUNCTION gtk_rc_style_ref ##### -->
<para>
-Increment the reference count of a #GtkRcStyle.
+Increments the reference count of a #GtkRcStyle.
</para>
@rc_style: a #GtkRcStyle
<!-- ##### FUNCTION gtk_rc_style_unref ##### -->
<para>
-Decrement the reference count of a #GtkRcStyle and
-free if the result is 0.
+Decrements the reference count of a #GtkRcStyle and
+frees if the result is 0.
</para>
@rc_style: a #GtkRcStyle
That string will then be used to display the scale's value.
Here's an example signal handler which displays a value 1.0 as
with "-->1.0<--".
-<programlisting>
+<informalexample><programlisting>
static gchar*
format_value_callback (GtkScale *scale,
gdouble value)
return g_strdup_printf ("-->%0.*g<--",
gtk_scale_get_digits (scale), value);
}
-</programlisting>
+</programlisting></informalexample>
</para>
@scale: the object which received the signal.
<!-- ##### FUNCTION gtk_target_list_new ##### -->
<para>
-Create a new #GtkTargetList from an array of #GtkTargetEntry.
+Creates a new #GtkTargetList from an array of #GtkTargetEntry.
</para>
@targets: Pointer to an array of #GtkTargetEntry
<!-- ##### FUNCTION gtk_target_list_ref ##### -->
<para>
-Increase the reference count of a #GtkTargetList by one.
+Increases the reference count of a #GtkTargetList by one.
</para>
@list: a #GtkTargetList
<!-- ##### FUNCTION gtk_target_list_unref ##### -->
<para>
-Decrease the reference count of a #GtkTargetList by one.
+Decreases the reference count of a #GtkTargetList by one.
If the resulting reference count is zero, free the list.
</para>
<!-- ##### FUNCTION gtk_target_list_add ##### -->
<para>
-Add another target to a #GtkTargetList
+Adds another target to a #GtkTargetList.
</para>
@list: a #GtkTargetList
<!-- ##### FUNCTION gtk_target_list_add_table ##### -->
<para>
-Add a table of #GtkTargetEntry into a target list
+Adds a table of #GtkTargetEntry into a target list.
</para>
@list: a #GtkTargetList
<!-- ##### FUNCTION gtk_target_list_remove ##### -->
<para>
-Remove a target from a target list
+Removes a target from a target list.
</para>
@list: a #GtkTargetList
<!-- ##### FUNCTION gtk_target_list_find ##### -->
<para>
-Look up a given target in a #GtkTargetList
+Looks up a given target in a #GtkTargetList.
</para>
@list: a #GtkTargetList
<!-- ##### FUNCTION gtk_selection_owner_set ##### -->
<para>
-Claim ownership of a given selection for a particular widget,
+Claims ownership of a given selection for a particular widget,
or, if @widget is %NULL, release ownership of the selection.
</para>
<!-- ##### FUNCTION gtk_selection_add_target ##### -->
<para>
-Add specified target to the list of supported targets for a
+Adds specified target to the list of supported targets for a
given widget and selection.
</para>
<!-- ##### FUNCTION gtk_selection_add_targets ##### -->
<para>
-Add a table of targets to the list of supported targets
+Adds a table of targets to the list of supported targets
for a given widget and selection.
</para>
<!-- ##### FUNCTION gtk_selection_convert ##### -->
<para>
-Request the contents of a selection. When received,
+Requests the contents of a selection. When received,
a "selection_received" signal will be generated.
</para>
@selection: Which selection to get
@target: Form of information desired (e.g., STRING)
@time: Time of request (usually of triggering event)
- In emergency, you could use GDK_CURRENT_TIME
-@Returns: TRUE if requested succeeded. FALSE if we could not process
+ In emergency, you could use #GDK_CURRENT_TIME
+@Returns: %TRUE if requested succeeded. %FALSE if we could not process
request. (e.g., there was already a request in process for
this widget).
<!-- ##### FUNCTION gtk_selection_data_set ##### -->
<para>
-Store new data into a GtkSelectionData object. Should
-_only_ by called from a selection handler callback.
-Null terminates the stored data.
+Stores new data into a GtkSelectionData object. Should
+<emphasis>only</emphasis> by called from a selection handler callback.
+zero-terminates the stored data.
</para>
@selection_data:
<!-- ##### FUNCTION gtk_selection_data_copy ##### -->
<para>
-Make a copy of a #GtkSelection data structure and its
+Makes a copy of a #GtkSelection data structure and its
data.
</para>
<!-- ##### FUNCTION gtk_selection_data_free ##### -->
<para>
-Free a #GtkSelectionData structure returned from
+Frees a #GtkSelectionData structure returned from
gtk_selection_data_copy().
</para>
</para>
<para>
Signals are used by everyone, but they are only
-created on a per class basis-- so you should not call
+created on a per class basis -- so you should not call
call gtk_signal_new() unless you are writing
a new #GtkObject type. However, if you want to make a new signal
for an existing type, you may use gtk_object_class_user_signal_new()
<listitem><para>A class method, e.g. GtkButton::clicked.
More precisely it is a unique class-branch/signal-name pair.
This means you may not define a signal handler for a class which
-derives from GtkButton that is called clicked,
+derives from #GtkButton that is called clicked,
but it is okay to share signals names if they are separate in
the class tree.
</para></listitem>
<!-- ##### FUNCTION gtk_signal_new ##### -->
<para>
-Create a new signal type. (This is usually done in the
+Creates a new signal type. (This is usually done in the
class initializer.)
</para>
@name: the event name for the signal, e.g. "clicked".
-@signal_flags: a combination of GTK_RUN flags
+@signal_flags: a combination of #GTK_RUN flags
specifying detail of when the default handler is to be invoked.
You should at least specify #GTK_RUN_FIRST
or #GTK_RUN_LAST.
are identified just by the type of arguments they take:
for example, gtk_marshal_BOOL__STRING() describes a marshaller
which takes a string and returns a boolean value.
-@return_val: the type of return value, or GTK_TYPE_NONE for a signal
+@return_val: the type of return value, or #GTK_TYPE_NONE for a signal
without a return value.
@n_args:
-@Varargs: a list of GTK_TYPE_*, one for each parameter.
+@Varargs: a list of #GTK_TYPE_*, one for each parameter.
@Returns: the signal id.
<!-- # Unused Parameters # -->
@nparams: the number of parameter the handlers may take.
<!-- ##### FUNCTION gtk_signal_newv ##### -->
<para>
-Create a new signal type. (This is usually done in a
+Creates a new signal type. (This is usually done in a
class initializer.)
</para>
<para>
@name: the name of the signal to create.
@signal_flags: see gtk_signal_new().
-@object_type: the type of GtkObject to associate the signal with.
+@object_type: the type of #GtkObject to associate the signal with.
@function_offset: how many bytes the function pointer is in
the class structure for this type.
@marshaller:
-@return_val: the type of the return value, or GTK_TYPE_NONE if
+@return_val: the type of the return value, or #GTK_TYPE_NONE if
you don't want a return value.
@n_args:
@args:
<!-- ##### MACRO gtk_signal_name ##### -->
<para>
-Given the signal's identifier, find its name.
+Given the signal's identifier, finds its name.
</para>
<para>
Two different signals may have the same name, if they have differing types.
</para>
@signal_id: the signal's identifying number.
-@Returns: the signal name, or NULL if the signal number was invalid.
+@Returns: the signal name, or %NULL if the signal number was invalid.
<!-- ##### FUNCTION gtk_signal_emit ##### -->
<para>
-Emit a signal. This causes the default handler and user-defined
+Emits a signal. This causes the default handler and user-defined
handlers to be run.
</para>
<para>
<para>
1. Calls the default handler and the user-connected handlers.
The default handler will be called first if
-GTK_RUN_FIRST is set, and last if GTK_RUN_LAST is set.
+#GTK_RUN_FIRST is set, and last if #GTK_RUN_LAST is set.
</para>
<para>
2. Calls all handlers connected with the "after" flag set.
<!-- ##### FUNCTION gtk_signal_emit_by_name ##### -->
<para>
-Emit a signal. This causes the default handler and user-connected
+Emits a signal. This causes the default handler and user-connected
handlers to be run.
</para>
<!-- ##### FUNCTION gtk_signal_emitv ##### -->
<para>
-Emit a signal. This causes the default handler and user-connected
+Emits a signal. This causes the default handler and user-connected
handlers to be run. This differs from gtk_signal_emit() by taking
an array of GtkArgs instead of using C's varargs mechanism.
</para>
<!-- ##### FUNCTION gtk_signal_emitv_by_name ##### -->
<para>
-Emit a signal by name. This causes the default handler and user-connected
+Emits a signal by name. This causes the default handler and user-connected
handlers to be run. This differs from gtk_signal_emit() by taking
an array of GtkArgs instead of using C's varargs mechanism.
</para>
<!-- ##### MACRO gtk_signal_connect ##### -->
<para>
-Attach a function pointer and user data to a signal for
+Attaches a function pointer and user data to a signal for
a particular object.
</para>
<para>
-The GtkSignalFunction takes a <StructName>GtkObject</StructName> as its first parameter.
+The #GtkSignalFunction takes a #GtkObject as its first parameter.
It will be the same object as the one you're connecting
-the hook to. The func_data will be passed as the last parameter
+the hook to. The @func_data will be passed as the last parameter
to the hook.
</para>
<para>
</para>
<informalexample>
<programlisting>
-static void button_clicked_int(GtkButton* button, gpointer func_data)
+static void button_clicked_int (GtkButton* button, gpointer func_data)
{
- g_print("button pressed: %d\n", GPOINTER_TO_INT(func_data));
+ g_print ("button pressed: %d\n", GPOINTER_TO_INT (func_data));
}
/* By calling this function, you will make the g_print above
* execute, printing the number passed as `to_print'. */
-static void attach_print_signal(GtkButton* button, gint to_print)
+static void attach_print_signal (GtkButton* button, gint to_print)
{
- gtk_signal_connect(GTK_OBJECT(button), "clicked",
- GTK_SIGNAL_FUNC(button_clicked_int),
- GINT_TO_POINTER(to_print));
+ gtk_signal_connect (GTK_OBJECT (button), "clicked",
+ GTK_SIGNAL_FUNC (button_clicked_int),
+ GINT_TO_POINTER (to_print));
}
</programlisting>
</informalexample>
<!-- ##### MACRO gtk_signal_connect_after ##### -->
<para>
-Attach a function pointer and user data to a signal
+Attaches a function pointer and user data to a signal
so that this handler will be called after the other handlers.
</para>
</para>
<informalexample>
<programlisting>
-gtk_signal_connect_object(button, "clicked", gtk_widget_show, window);
+gtk_signal_connect_object (button, "clicked", gtk_widget_show, window);
</programlisting>
</informalexample>
<!-- ##### MACRO gtk_signal_connect_object_after ##### -->
<para>
-Attach a signal hook to a signal, passing in an alternate
+Attaches a signal hook to a signal, passing in an alternate
object as the first parameter, and guaranteeing
that the default handler and all normal
handlers are called first.
<!-- ##### FUNCTION gtk_signal_connect_full ##### -->
<para>
-Attach a function pointer and user data to a signal with
+Attaches a function pointer and user data to a signal with
more control.
</para>
<!-- ##### FUNCTION gtk_signal_connect_while_alive ##### -->
<para>
-Attach a function pointer and another GtkObject to a signal.
+Attaches a function pointer and another #GtkObject to a signal.
</para>
<para>
This function takes an object whose "destroy" signal
(Instead you may call gtk_signal_disconnect_by_data(), if you want
to explicitly delete all attachments to this object. This
is perhaps not recommended since it could be confused
-with an integer masquerading as a pointer (through GINT_AS_POINTER).)
+with an integer masquerading as a pointer (through GINT_TO_POINTER()).)
</para>
@object: the object that emits the signal.
<!-- ##### MACRO gtk_signal_disconnect ##### -->
<para>
-Destroy a user-defined handler connection.
+Destroys a user-defined handler connection.
</para>
@object: the object which the handler pertains to.
<!-- ##### MACRO gtk_signal_disconnect_by_func ##### -->
<para>
-Destroy all connections for a particular object, with
+Destroys all connections for a particular object, with
the given function-pointer and user-data.
</para>
<!-- ##### MACRO gtk_signal_disconnect_by_data ##### -->
<para>
-Destroy all connections for a particular object, with
+Destroys all connections for a particular object, with
the given user-data.
</para>
<!-- ##### MACRO gtk_signal_handler_block ##### -->
<para>
-Prevent an user-defined handler from being invoked. All other
+Prevents a user-defined handler from being invoked. All other
signal processing will go on as normal, but this particular
handler will ignore it.
</para>
<!-- ##### MACRO gtk_signal_handler_block_by_func ##### -->
<para>
-Prevent a user-defined handler from being invoked, by reference to
+Prevents a user-defined handler from being invoked, by reference to
the user-defined handler's function pointer and user data. (It may result in
multiple hooks being blocked, if you've called connect multiple times.)
</para>
<!-- ##### MACRO gtk_signal_handler_block_by_data ##### -->
<para>
-Prevent all user-defined handlers with a certain user data from being invoked.
+Prevents all user-defined handlers with a certain user data from being invoked.
</para>
@object: the object which emits the signal we want to block.
<!-- ##### MACRO gtk_signal_handler_unblock ##### -->
<para>
-Undo a block, by connection id. Note that undoing a block doesn't
+Undoes a block, by connection id. Note that undoing a block doesn't
necessarily make the hook callable, because if you block a
hook twice, you must unblock it twice.
</para>
<!-- ##### MACRO gtk_signal_handler_unblock_by_func ##### -->
<para>
-Undo a block, by function pointer and data.
+Undoes a block, by function pointer and data.
Note that undoing a block doesn't
necessarily make the hook callable, because if you block a
hook twice, you must unblock it twice.
<!-- ##### MACRO gtk_signal_handler_unblock_by_data ##### -->
<para>
-Undo block(s), to all signals for a particular object
+Undoes block(s), to all signals for a particular object
with a particular user-data pointer
</para>
have been added to its parent.
<example>
-<title> Obtaining the XID of a socket </title>
+<title>Obtaining the XID of a socket.</title>
<programlisting>
#include <gdk/gdkx.h>
-GtkWidget *socket = gtk_socket_new();
+GtkWidget *socket = gtk_socket_new (<!>);
gtk_widget_show (socket);
gtk_container_add (GTK_CONTAINER (parent), socket);
separate toplevel window. You can check if the plug
has been created by examining the
<StructField>plug_window</StructField> field of the
-#GtkSocket structure. If this field is non-NULL,
+#GtkSocket structure. If this field is non-%NULL,
then the plug has been successfully created inside
of the socket.
</para>
<!-- ##### SECTION Long_Description ##### -->
<para>
-A #GtkSpinButton is an ideal way to allow the user to set the value of some attribute. Rather than having to directly type a number into a #GtkEntry, #GtkSpinButton allows the user to click on one of two arrows to increment or decrement the displayed value. A value can still be typed in, with the bonus that it can be checked to ensure it is in a given range.
+A #GtkSpinButton is an ideal way to allow the user to set the value of some
+attribute. Rather than having to directly type a number into a #GtkEntry,
+#GtkSpinButton allows the user to click on one of two arrows to increment or
+decrement the displayed value. A value can still be typed in, with the bonus
+that it can be checked to ensure it is in a given range.
</para>
<para>
-The main properties of a #GtkSpinButton are through a #GtkAdjustment. See the #GtkAdjustment section for more details about an adjustment's properties.
+The main properties of a #GtkSpinButton are through a #GtkAdjustment. See the
+#GtkAdjustment section for more details about an adjustment's properties.
</para>
<para>
<example>
-<title>Using a GtkSpinButton to get an integer.</title>
+<title>Using a <structname>GtkSpinButton</structname> to get an integer.</title>
<programlisting>
/* Provides a function to retrieve an integer value from a GtkSpinButton
return gtk_spin_button_get_value_as_int (a_spinner);
}
-void create_integer_spin_button(void) {
+void create_integer_spin_button (void) {
GtkWidget *window, *spinner;
GtkAdjustment *spinner_adj;
- spinner_adj = (GtkAdjustment *) gtk_adjustment_new(50.0, 0.0, 100.0, 1.0, 5.0, 5.0);
+ spinner_adj = (GtkAdjustment *) gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 5.0);
- window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
+ window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
gtk_container_set_border_width (GTK_CONTAINER (window), 5);
/* creates the spinner, with no decimal places */
spinner = gtk_spin_button_new (spinner_adj, 1.0, 0);
- gtk_container_add (GTK_CONTAINER(window), spinner);
+ gtk_container_add (GTK_CONTAINER (window), spinner);
gtk_widget_show_all (window);
return;
<para>
<example>
-<title>Using a GtkSpinButton to get a floating point value.</title>
+<title>Using a <structname>GtkSpinButton</structname> to get a floating point value.</title>
<programlisting>
/* Provides a function to retrieve a floating point value from a
return gtk_spin_button_get_value_as_float (a_spinner);
}
-void create_floating_spin_button(void) {
+void create_floating_spin_button (void) {
GtkWidget *window, *spinner;
GtkAdjustment *spinner_adj;
- spinner_adj = (GtkAdjustment *) gtk_adjustment_new(2.500, 0.0, 5.0, 0.001, 0.1, 0.1);
+ spinner_adj = (GtkAdjustment *) gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.1);
- window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
+ window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
gtk_container_set_border_width (GTK_CONTAINER (window), 5);
/* creates the spinner, with three decimal places */
spinner = gtk_spin_button_new (spinner_adj, 0.001, 3);
- gtk_container_add (GTK_CONTAINER(window), spinner);
+ gtk_container_add (GTK_CONTAINER (window), spinner);
gtk_widget_show_all (window);
return;
<!-- ##### STRUCT GtkSpinButton ##### -->
<para>
-<structfield>entry</structfield> is the #GtkEntry part of the #GtkSpinButton widget, and can be used accordingly. All other fields contain private data and should only be modified using the functions below.
+<structfield>entry</structfield> is the #GtkEntry part of the #GtkSpinButton
+widget, and can be used accordingly. All other fields contain private data
+and should only be modified using the functions below.
</para>
<!-- ##### SECTION Long_Description ##### -->
<para>
-The GtkTable functions allow the programmer to arrange widgets in rows and
+The #GtkTable functions allow the programmer to arrange widgets in rows and
columns, making it easy to align many widgets next to each other,
horizontally and vertically.
</para>
<!-- ##### STRUCT GtkTable ##### -->
<para>
-The GtkTable structure holds the data for the actual table itself.
+The <structname>GtkTable</structname> structure holds the data for the actual table itself.
<structfield>children</structfield> is a #GList of all the widgets the table contains. <structfield>rows</structfield> and <structfield>columns</structfield> are pointers to #GtkTableRowCol structures, which contain the default spacing and expansion details for the #GtkTable's rows and columns, respectively.
</para>
@rows: The number of rows the new table should have.
@columns: The number of columns the new table should have.
-@homogeneous: If set to TRUE, all table cells are resized to the size of the cell
+@homogeneous: If set to %TRUE, all table cells are resized to the size of the cell
containing the largest widget.
@Returns: A pointer to the the newly created table widget.
<!-- ##### FUNCTION gtk_table_set_row_spacing ##### -->
<para>
-changes the space between a given table row and its surrounding rows.
+Changes the space between a given table row and its surrounding rows.
</para>
@table: a #GtkTable containing the row whose properties you wish to change.
<!-- ##### FUNCTION gtk_table_set_col_spacing ##### -->
<para>
-alters the amount of space between a given table column and the adjacent columns.
+Alters the amount of space between a given table column and the adjacent columns.
</para>
@table: a #GtkTable.
<!-- ##### FUNCTION gtk_table_set_row_spacings ##### -->
<para>
-sets the space between every row in @table equal to @spacing.
+Sets the space between every row in @table equal to @spacing.
</para>
@table: a #GtkTable.
<!-- ##### FUNCTION gtk_table_set_col_spacings ##### -->
<para>
-sets the space between every column in @table equal to @spacing.
+Sets the space between every column in @table equal to @spacing.
</para>
@table: a #GtkTable.
<!-- ##### FUNCTION gtk_table_set_homogeneous ##### -->
<para>
-changes the homogenous property of table cells. Ie. whether all cells are an equal size or not.
+Changes the homogenous property of table cells, ie. whether all cells are an equal size or not.
</para>
-@table: The GtkTable you wish to set the homogeneous properties of.
-@homogeneous: Set to TRUE to ensure all table cells are the same size. Set
-to FALSE if this is not your desired behaviour.
+@table: The #GtkTable you wish to set the homogeneous properties of.
+@homogeneous: Set to %TRUE to ensure all table cells are the same size. Set
+to %FALSE if this is not your desired behaviour.
<!-- ##### FUNCTION gtk_table_get_default_row_spacing ##### -->
<!-- ##### ARG GtkTable:n-rows ##### -->
<para>
-set or retrieve the number of rows in a table.
+Sets or retrieves the number of rows in a table.
</para>
<!-- ##### ARG GtkTable:n-columns ##### -->
<para>
-set or retrieve the number of columnsin a table.
+Sets or retrieves the number of columns in a table.
</para>
<!-- ##### ARG GtkTable:column-spacing ##### -->
<para>
-set or retrieve the number of pixels of space between each column.
+Sets or retrieves the number of pixels of space between columns.
</para>
<!-- ##### ARG GtkTable:row-spacing ##### -->
<para>
-set or retrieve the number of pixels of space between each row.
+Sets or retrieves the number of pixels of space between rows.
</para>
<!-- ##### ARG GtkTable:homogeneous ##### -->
<para>
-whether each cell in the table should be the same size or not.
+Whether each cell in the table should be the same size or not.
</para>
@tip_text: the widget's tooltip.
@tip_private: the widget's private tooltip (see gtk_tooltips_set_tip()).
@event: the button press or button release event.
-@Returns: TRUE if the query should be stopped.
+@Returns: %TRUE if the query should be stopped.
<!-- ##### ARG GtkTipsQuery:emit-always ##### -->
<para>
-TRUE if the widget-entered and widget-selected signals are emitted even when
+%TRUE if the widget-entered and widget-selected signals are emitted even when
the widget has no tooltip set.
</para>
To simply switch the state of a toggle button, use gtk_toggle_button_toggled.
</para>
<example>
-<title>Creating two #GtkToggleButton widgets.</title>
+<title>Creating two <structname>GtkToggleButton</structname> widgets.</title>
<programlisting>
-void make_toggles(void) {
+void make_toggles (void) {
GtkWidget *dialog, *toggle1, *toggle2;
- dialog = gtk_dialog_new();
- toggle1 = gtk_toggle_button_new_with_label("Hi, i'm a toggle button.");
+ dialog = gtk_dialog_new (<!>);
+ toggle1 = gtk_toggle_button_new_with_label ("Hi, i'm a toggle button.");
/* Makes this toggle button invisible */
gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle1), TRUE);
gtk_signal_connect (GTK_OBJECT (toggle1), "toggled",
GTK_SIGNAL_FUNC (output_state), NULL);
- gtk_box_pack_start (GTK_BOX (GTK_DIALOG(dialog)->action_area),
+ gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area),
toggle1, FALSE, FALSE, 2);
- toggle2 = gtk_toggle_button_new_with_label("Hi, i'm another toggle button.");
+ toggle2 = gtk_toggle_button_new_with_label ("Hi, i'm another toggle button.");
gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle2), FALSE);
gtk_signal_connect (GTK_OBJECT (toggle2), "toggled",
GTK_SIGNAL_FUNC (output_state), NULL);
- gtk_box_pack_start (GTK_BOX (GTK_DIALOG(dialog)->action_area),
+ gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area),
toggle2, FALSE, FALSE, 2);
gtk_widget_show_all (dialog);
<!-- ##### FUNCTION gtk_toggle_button_set_mode ##### -->
<para>
-Determines whether or not the toggle button is drawn on screen. The default mode is FALSE, which results in the button being displayed. To make the button invisible, set <structfield>draw_indicator</structfield> to TRUE.
+Determines whether or not the toggle button is drawn on screen. The default mode is %FALSE, which results in the button being displayed. To make the button invisible, set <structfield>draw_indicator</structfield> to %TRUE.
</para>
@toggle_button: a #GtkToggleButton.
-@draw_indicator: TRUE or FALSE.
+@draw_indicator: %TRUE or %FALSE.
<!-- ##### FUNCTION gtk_toggle_button_get_mode ##### -->
<!-- ##### MACRO gtk_toggle_button_set_state ##### -->
<para>
-This is a deprecated macro, and is only maintained for compatability reasons.
+This is a deprecated macro, and is only maintained for compatibility reasons.
</para>
<!-- ##### FUNCTION gtk_toggle_button_get_active ##### -->
<para>
-Queries a #GtkToggleButton and returns it's current state. Returns TRUE if
-the toggle button is pressed in and FALSE if it is raised.
+Queries a #GtkToggleButton and returns it's current state. Returns %TRUE if
+the toggle button is pressed in and %FALSE if it is raised.
</para>
@toggle_button: a #GtkToggleButton.
<!-- ##### FUNCTION gtk_toggle_button_set_active ##### -->
<para>
-Sets the status of the toggle button. Set to TRUE if you want the
-GtkToggleButton to be 'pressed in', and FALSE to raise it.
+Sets the status of the toggle button. Set to %TRUE if you want the
+GtkToggleButton to be 'pressed in', and %FALSE to raise it.
This action causes the toggled signal to be emitted.
</para>
@toggle_button: a #GtkToggleButton.
-@is_active: TRUE or FALSE.
+@is_active: %TRUE or %FALSE.
<!-- ##### FUNCTION gtk_toggle_button_get_inconsistent ##### -->
<!-- ##### ARG GtkToggleButton:draw-indicator ##### -->
<para>
-A value of TRUE causes the toggle button to be invisible. FALSE displays it
+A value of %TRUE causes the toggle button to be invisible. %FALSE displays it.
again.
</para>
<note>
<para>
Tooltips can only be set on widgets which have their own X window.
-To check if a widget has its own window use 'GTK_WIDGET_NO_WINDOW (widget)'.
+To check if a widget has its own window use <literal>GTK_WIDGET_NO_WINDOW (widget)</literal>.
To add a tooltip to a widget that doesn't have its own window, place the
widget inside a #GtkEventBox and add a tooltip to that instead.
</para>
</note>
<para>
-The default appearance of all tooltips in a program is determined by the current gtk theme that the user has selected.
+The default appearance of all tooltips in a program is determined by the current GTK+ theme that the user has selected.
</para>
<para>
Information about the tooltip (if any) associated with an arbitrary widget can be retrieved using gtk_tooltips_data_get().
GtkWidget *load_button, *save_button, *hbox;
GtkTooltips *button_bar_tips;
- button_bar_tips = gtk_tooltips_new();
+ button_bar_tips = gtk_tooltips_new (<!>);
- /* Create the buttons and pack them into a #GtkHBox */
- hbox = gtk_hbox_new(TRUE, 2);
+ /* Create the buttons and pack them into a GtkHBox */
+ hbox = gtk_hbox_new (TRUE, 2);
- load_button = gtk_button_new_with_label("Load a file");
- gtk_box_pack_start(GTK_BOX (hbox), load_button, TRUE, TRUE, 2);
- gtk_widget_show(load_button);
+ load_button = gtk_button_new_with_label ("Load a file");
+ gtk_box_pack_start (GTK_BOX (hbox), load_button, TRUE, TRUE, 2);
+ gtk_widget_show (load_button);
- save_button = gtk_button_new_with_label("Save a file");
- gtk_box_pack_start(GTK_BOX (hbox), save_button, TRUE, TRUE, 2);
- gtk_widget_show(save_button);
- gtk_widget_show(hbox);
+ save_button = gtk_button_new_with_label ("Save a file");
+ gtk_box_pack_start (GTK_BOX (hbox), save_button, TRUE, TRUE, 2);
+ gtk_widget_show (save_button);
+ gtk_widget_show (hbox);
/* Add the tips */
- gtk_tooltips_set_tip(GTK_TOOLTIPS (button_bar_tips), load_button,
+ gtk_tooltips_set_tip (GTK_TOOLTIPS (button_bar_tips), load_button,
"Load a new document into this window",
"Requests the filename of a document.
This will then be loaded into the current
window, replacing the contents of whatever
is already loaded.");
- gtk_tooltips_set_tip(GTK_TOOLTIPS (button_bar_tips), save_button,
+ gtk_tooltips_set_tip (GTK_TOOLTIPS (button_bar_tips), save_button,
"Saves the current document to a file",
"If you have saved the document previously,
then the new version will be saved over the
</para>
@widget: a #GtkWidget.
-@Returns: a #GtkTooltipsData struct, or NULL if the widget has no tooltip.
+@Returns: a #GtkTooltipsData struct, or %NULL if the widget has no tooltip.
<!-- ##### FUNCTION gtk_tooltips_force_window ##### -->
<orderedlist>
<listitem>
<para>
-<literal>gtk_window_set_policy(GTK_WINDOW(window), FALSE, TRUE, FALSE)</literal>
+<literal>gtk_window_set_policy (GTK_WINDOW (window), FALSE, TRUE, FALSE)</literal>
means that the window is user-resizable.
</para>
</listitem>
<listitem>
<para>
-<literal>gtk_window_set_policy(GTK_WINDOW(window), FALSE, FALSE, TRUE)</literal>
+<literal>gtk_window_set_policy (GTK_WINDOW (window), FALSE, FALSE, TRUE)</literal>
means that the window's size is program-controlled, and should simply match
the current size request of the window's children.
</para>
<para>
The basic ugly truth of this function is that it should be simply:
<programlisting>
- void gtk_window_set_resizable(GtkWidget* window, gboolean setting);
+ void gtk_window_set_resizable (GtkWidget* window, gboolean setting);
</programlisting>
...which is why GTK+ 2.0 introduces gtk_window_set_resizable(), which you
should use instead of gtk_window_set_policy().
</para>
<para>
-If set to TRUE, the @allow_grow parameter allows the user to expand the window
-beyond the size request of its child widgets. If @allow_grow is TRUE, be sure to
+If set to %TRUE, the @allow_grow parameter allows the user to expand the window
+beyond the size request of its child widgets. If @allow_grow is %TRUE, be sure to
check that your child widgets work properly as the window is resized.
</para>
shrink to fit the size request of its children if it's too large; the
@auto_shrink parameter causes the window to shrink when child widgets have too
much space. @auto_shrink is normally used with the second of the two window
-policies mentioned above. That is, set @auto_shrink to TRUE if you want the
+policies mentioned above. That is, set @auto_shrink to %TRUE if you want the
window to have a fixed, always-optimal size determined by your program.
</para>
<para>
Note that @auto_shrink doesn't do anything if @allow_shrink and @allow_grow are
-both set to FALSE.
+both set to %FALSE.
</para>
<para>
-Neither of the two suggested window policies set the @allow_shrink paramter to
-TRUE. If @allow_shrink is TRUE, the user can shrink the window so that its
+Neither of the two suggested window policies set the @allow_shrink parameter to
+%TRUE. If @allow_shrink is %TRUE, the user can shrink the window so that its
children do not receive their full size request; this is basically a bad thing,
because most widgets will look wrong if this happens. Furthermore GTK+ has a
tendency to re-expand the window if size is recalculated for any reason. The
-upshot is that @allow_shrink should always be set to FALSE.
+upshot is that @allow_shrink should always be set to %FALSE.
</para>
<para>
<!-- ##### MACRO gtk_window_position ##### -->
<para>
-Deperecated alias for gtk_window_set_position().
+Deprecated alias for gtk_window_set_position().
</para>
+2001-12-12 Matthias Clasen <matthiasc@poet.de>
+
+ * gdk-pixbuf-io.c: Markup fixes.
+
2001-12-12 Matthias Clasen <matthiasc@poet.de>
* Makefile.am (INCLUDES): Define G_LOG_DOMAIN. (#66412)
* @error: Return location for an error
*
* Creates a new pixbuf by loading an image from a file. The file format is
- * detected automatically. If NULL is returned, then @error will be set.
+ * detected automatically. If %NULL is returned, then @error will be set.
* Possible errors are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains.
*
- * Return value: A newly-created pixbuf with a reference count of 1, or NULL if
+ * Return value: A newly-created pixbuf with a reference count of 1, or %NULL if
* any of several error conditions occurred: the file could not be opened,
* there was no loader for the file's format, there was not enough memory to
* allocate the image buffer, or the image file contained invalid data.
* @Varargs: list of key-value save options
*
* Saves pixbuf to a file in @type, which is currently "jpeg" or
- * "png". If @error is set, FALSE will be returned. Possible errors include
+ * "png". If @error is set, %FALSE will be returned. Possible errors include
* those in the #GDK_PIXBUF_ERROR domain and those in the #G_FILE_ERROR domain.
*
- * The variable argument list should be NULL-terminated; if not empty,
+ * The variable argument list should be %NULL-terminated; if not empty,
* it should contain pairs of strings that modify the save
* parameters. For example:
- *
- * <programlisting>
+ * <informalexample><programlisting>
* gdk_pixbuf_save (pixbuf, handle, "jpeg", &error,
* "quality", "100", NULL);
- * </programlisting>
+ * </programlisting></informalexample>
*
* Currently only few parameters exist. JPEG images can be saved with a
* "quality" parameter; its value should be in the range [0,100].
* @pixbuf: pointer to GdkPixbuf.
* @filename: Name of file to save.
* @type: name of file format.
- * @option_keys: name of options to set, NULL-terminated
+ * @option_keys: name of options to set, %NULL-terminated
* @option_values: values for named options
- * @error: return location for error, or NULL
+ * @error: return location for error, or %NULL
*
* Saves pixbuf to a file in @type, which is currently "jpeg" or "png".
- * If @error is set, FALSE will be returned. See gdk_pixbuf_save () for more
+ * If @error is set, %FALSE will be returned. See gdk_pixbuf_save () for more
* details.
*
* Return value: whether an error was set
* so the first button in the list will be the leftmost button in the dialog.
*
* Here's a simple example:
- * <programlisting>
+ * <informalexample><programlisting>
* GtkWidget *dialog = gtk_dialog_new_with_buttons ("My dialog",
* main_app_window,
* GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT,
* GTK_STOCK_CANCEL,
* GTK_RESPONSE_REJECT,
* NULL);
- * </programlisting>
+ * </programlisting></informalexample>
*
* Return value: a new #GtkDialog
**/
* @response_id: a response ID
* @setting: %TRUE for sensitive
*
- * Calls gtk_widget_set_sensitive (widget, @setting) for each
- * widget in the dialog's action area with the given @response_id.
+ * Calls <literal>gtk_widget_set_sensitive (widget, @setting)</literal>
+ * for each widget in the dialog's action area with the given @response_id.
* A convenient way to sensitize/desensitize dialog buttons.
**/
void
* destroying the dialog if you wish to do so.
*
* Typical usage of this function might be:
- * <programlisting>
+ * <informalexample><programlisting>
* gint result = gtk_dialog_run (GTK_DIALOG (dialog));
* switch (result)
* {
* case GTK_RESPONSE_ACCEPT:
- * do_application_specific_something ();
+ * do_application_specific_something (<!>);
* break;
* default:
- * do_nothing_since_dialog_was_cancelled ();
+ * do_nothing_since_dialog_was_cancelled (<!>);
* break;
* }
* gtk_widget_destroy (dialog);
- * </programlisting>
+ * </programlisting></informalexample>
*
* Return value: response ID
**/
/**
* gtk_rc_set_default_files:
- * @filenames: A %NULL terminated list of filenames.
+ * @filenames: A %NULL-terminated list of filenames.
*
* Sets the list of files that GTK+ will read at the
- * end of gtk_init()
+ * end of gtk_init().
**/
void
gtk_rc_set_default_files (gchar **filenames)
* gtk_rc_get_default_files:
*
* Retrieves the current list of RC files that will be parsed
- * at the end of gtk_init()
+ * at the end of gtk_init().
*
- * Return value: A NULL terminated array of filenames. This memory
+ * Return value: A %NULL-terminated array of filenames. This memory
* is owned by GTK+ and must not be freed by the application.
- * If you want to store this information, you should make a
- * copy.
+ * If you want to store this information, you should make a copy.
**/
gchar **
gtk_rc_get_default_files (void)
* gtk_rc_style_copy:
* @orig: the style to copy
*
- * Make a copy of the specified #GtkRcStyle. This function
+ * Makes a copy of the specified #GtkRcStyle. This function
* will correctly copy an rc style that is a member of a class
* derived from #GtkRcStyle.
*
* @force_load: load whether or not anything changed
*
* If the modification time on any previously read file
- * for the given GtkSettings has changed, discard all style information
+ * for the given #GtkSettings has changed, discard all style information
* and then reread all previously read RC files.
*
* Return value: %TRUE if the files were reread.
* @widget_path: the widget path to use when looking up the style, or %NULL
* @class_path: the class path to use when looking up the style, or %NULL
* @type: a type that will be used along with parent types of this type
- * when matching against class styles, or G_TYPE_NONE
+ * when matching against class styles, or #G_TYPE_NONE
*
* Creates up a #GtkStyle from styles defined in a RC file by providing
* the raw components used in matching. This function may be useful
* would be items inside a GNOME canvas widget.
*
* The action of gtk_rc_get_style() is similar to:
- *
- * <programlisting>
+ * <informalexample><programlisting>
* gtk_widget_path (widget, NULL, &path, NULL);
* gtk_widget_class_path (widget, NULL, &class_path, NULL);
* gtk_rc_get_style_by_paths (gtk_widget_get_settings (widget), path, class_path,
* G_OBJECT_TYPE (widget));
- * </programlisting>
+ * </programlisting></informalexample>
*
* Return value: A style created by matching with the supplied paths,
- * or %NULL if nothign matching was specified and the default style should
+ * or %NULL if nothing matching was specified and the default style should
* be used. The returned value is owned by GTK+ as part of an internal cache,
* so you must call g_object_ref() on the returned value if you want to
* keep a reference to it.
* If the file is not found, it outputs a warning message using
* g_warning() and returns %NULL.
*
- * Return value:
+ * Return value: the filename.
**/
gchar*
gtk_rc_find_pixmap_in_path (GtkSettings *settings,
* @widget: a #GtkWidget
*
* Creates the GDK (windowing system) resources associated with a
- * widget. For example, widget->window will be created when a widget
+ * widget. For example, @widget->window will be created when a widget
* is realized. Normally realization happens implicitly; if you show
* a widget and all its parent containers, then the widget will be
* realized and mapped automatically.
*
* This function is only useful in widget implementations.
* Causes a widget to be unrealized (frees all GDK resources
- * associated with the widget, such as widget->window).
+ * associated with the widget, such as @widget->window).
*
**/
void
* Lists the closures used by @widget for accelerator group connections
* with gtk_accel_group_connect_by_path() or gtk_accel_group_connect().
* The closures can be used to monitor accelerator changes on @widget,
- * by connecting to the ::accel_changed signal of the #GtkAccelGroup
- * of a closure which can be found out with gtk_accel_group_from_accel_closure().
+ * by connecting to the ::accel_changed signal of the #GtkAccelGroup of a
+ * closure which can be found out with gtk_accel_group_from_accel_closure().
*/
GList*
gtk_widget_list_accel_closures (GtkWidget *widget)
* gtk_widget_region_intersect:
* @widget: a #GtkWidget
* @region: a #GdkRegion, in the same coordinate system as
- * widget->allocation. That is, relative to @widget->window
+ * @widget->allocation. That is, relative to @widget->window
* for %NO_WINDOW widgets; relative to the parent window
* of @widget->window for widgets with their own window.
* @returns: A newly allocated region holding the intersection of @widget
*
* Creates a new #PangoContext with the appropriate colormap,
* font description, and base direction for drawing text for
- * this widget. See also gtk_widget_get_pango_context()
+ * this widget. See also gtk_widget_get_pango_context().
*
* Return value: the new #PangoContext
**/
*
*
* Sets the position of a widget. The funny "u" in the name comes from
- * the "user position" hint specified by the X window system, and
+ * the "user position" hint specified by the X Window System, and
* exists for legacy reasons. This function doesn't work if a widget
* is inside a container; it's only really useful on #GtkWindow.
*
* gtk_widget_get_settings:
* @widget: a #GtkWidget
*
- * Get the settings object holding the settings (global property
+ * Gets the settings object holding the settings (global property
* settings, RC file information, etc) used for this widget.
*
* Return value: the relevant #GtkSettings object
* the corresponding gtk_widget_pop_composite_child() call.
*
* Here is a simple example:
- * <programlisting>
- * gtk_widget_push_composite_child ();
+ * <informalexample><programlisting>
+ * gtk_widget_push_composite_child (<!>);
* scrolled_window->hscrollbar = gtk_hscrollbar_new (hadjustment);
* gtk_widget_set_composite_name (scrolled_window->hscrollbar, "hscrollbar");
- * gtk_widget_pop_composite_child ();
+ * gtk_widget_pop_composite_child (<!>);
* gtk_widget_set_parent (scrolled_window->hscrollbar,
* GTK_WIDGET (scrolled_window));
* gtk_widget_ref (scrolled_window->hscrollbar);
- * </programlisting>
+ * </programlisting></informalexample>
**/
void
gtk_widget_push_composite_child (void)
* @offset_x: X position of shape mask with respect to @window.
* @offset_y: Y position of shape mask with respect to @window.
*
- * Sets a shape for this widget's gdk window. This allows for
+ * Sets a shape for this widget's GDK window. This allows for
* transparent windows etc., see gdk_window_shape_combine_mask()
* for more information.
**/
projects / gtk4.git / commitdiff